react-input-mask

What is react-input-mask?

The react-input-mask package is a versatile input masking library for React applications. It allows developers to create input fields with predefined formats, ensuring that users enter data in a consistent and expected manner. This is particularly useful for fields like phone numbers, dates, and credit card numbers.

What are react-input-mask's main functionalities?

Basic Input Masking

This feature allows you to create a basic input mask for phone numbers. The mask prop defines the format, and the input field will automatically enforce this format as the user types.

import React from 'react';
import InputMask from 'react-input-mask';

function PhoneInput() {
  return (
    <InputMask mask="[phone]" placeholder="Enter phone number" />
  );
}

export default PhoneInput;

Custom Masking Characters

This feature allows you to define custom masking characters. In this example, the mask includes both numbers and letters, and the maskChar prop specifies the character to use for unfilled positions.

import React from 'react';
import InputMask from 'react-input-mask';

function CustomMaskInput() {
  return (
    <InputMask mask="99-aaa-9999" maskChar="_" placeholder="Enter custom format" />
  );
}

export default CustomMaskInput;

Masking with Validation

This feature demonstrates how to use input masking with state management and validation. The input field is masked for a credit card number, and the value is managed using React's useState hook.

import React, { useState } from 'react';
import InputMask from 'react-input-mask';

function ValidatedInput() {
  const [value, setValue] = useState('');
  const handleChange = (e) => {
    setValue(e.target.value);
  };
  return (
    <InputMask mask="9999-9999-9999-9999" value={value} onChange={handleChange} placeholder="Enter credit card number" />
  );
}

export default ValidatedInput;

Other packages similar to react-input-mask

react-text-mask

react-text-mask is another popular library for input masking in React. It offers similar functionality to react-input-mask but also supports masking for other frameworks like Angular and Vue. It provides a flexible API and supports custom mask definitions.

cleave.js

cleave.js is a JavaScript library for formatting input fields. It supports a wide range of input types, including credit cards, phone numbers, and dates. Unlike react-input-mask, cleave.js is not limited to React and can be used with vanilla JavaScript or other frameworks.

imaskjs

imaskjs is a versatile input masking library that supports a wide range of input types and custom masks. It offers a rich set of features, including dynamic masks and pattern matching. imaskjs can be used with React, Angular, Vue, and vanilla JavaScript.

README

react-input-mask

Input masking component for React. Made with attention to UX.

This is a development branch for version 3.0. For the latest stable version see v2 branch.

Demo

Table of Contents

• Installation
• Usage
• Properties
• Known Issues

Installation

npm install react-input-mask@next --save

react-input-mask requires React 16.8.0 or later. If you need support for older versions, use version 2.

Usage

import React from "react"
import InputMask from "react-input-mask";

function DateInput(props) {
  return <InputMask mask="99/99/9999" onChange={props.onChange} value={props.value} />;
}

Properties

Name	Type	Default	Description
mask	{String|Array<String, RegExp>}		Mask format
maskPlaceholder	{String}	_	Placeholder to cover unfilled parts of the mask
alwaysShowMask	{Boolean}	false	Whether mask prefix and placeholder should be displayed when input is empty and has no focus
beforeMaskedStateChange	{Function}		Function to modify value and selection before applying mask
children	{ReactElement}		Custom render function for integration with other input components

mask

Mask format. Can be either a string or array of characters and regular expressions.

<InputMask mask="99/99/99" />

Simple masks can be defined as strings. The following characters will define mask format:

Character	Allowed input
9	0-9
a	a-z, A-Z
*	0-9, a-z, A-Z

Any format character can be escaped with a backslash.

More complex masks can be defined as an array of regular expressions and constant characters.

// Canadian postal code mask
const firstLetter = /(?!.*[DFIOQU])[A-VXY]/i;
const letter = /(?!.*[DFIOQU])[A-Z]/i;
const digit = /[0-9]/;
const mask = [firstLetter, digit, letter, " ", digit, letter, digit];
return <InputMask mask={mask} />;

maskPlaceholder

// Will be rendered as 12/--/--
<InputMask mask="99/99/99" maskPlaceholder="-" value="12" />

// Will be rendered as 12/mm/yy
<InputMask mask="99/99/99" maskPlaceholder="dd/mm/yy" value="12" />

// Will be rendered as 12/
<InputMask mask="99/99/99" maskPlaceholder={null} value="12" />

Character or string to cover unfilled parts of the mask. Default character is "_". If set to null or empty string, unfilled parts will be empty as in a regular input.

alwaysShowMask

If enabled, mask prefix and placeholder will be displayed even when input is empty and has no focus.

beforeMaskedStateChange

In case you need to customize masking behavior, you can provide beforeMaskedStateChange function to change masked value and cursor position before it's applied to the input.

It receieves an object with previousState, currentState and nextState properties. Each state is an object with value and selection properites where value is a string and selection is an object containing start and end positions of the selection.

1. previousState: Input state before change. Only defined on change event.
2. currentState: Current raw input state. Not defined during component render.
3. nextState: Input state with applied mask. Contains value and selection fields.

Selection positions will be null if input isn't focused and during rendering.

beforeMaskedStateChange must return a new state with value and selection.

// Trim trailing slashes
function beforeMaskedStateChange({ nextState }) {
  let { value } = nextState;
  if (value.endsWith("/")) {
    value = value.slice(0, -1);
  }

  return {
    ...nextState,
    value
  };
}

return <InputMask mask="99/99/99" maskPlaceholder={null} beforeMaskedStateChange={beforeMaskedStateChange} />;

Please note that beforeMaskedStateChange executes more often than onChange and must be pure.

children

To use another component instead of regular <input /> provide it as children. The following properties, if used, should always be defined on the InputMask component itself: onChange, onMouseDown, onFocus, onBlur, value, disabled, readOnly.

import React from 'react';
import InputMask from 'react-input-mask';
import MaterialInput from '@material-ui/core/Input';

// Will work fine
function Input(props) {
  return (
    <InputMask mask="99/99/9999" value={props.value} onChange={props.onChange}>
      <MaterialInput type="tel" disableUnderline />
    </InputMask>
  );
}

// Will throw an error because InputMask's and children's onChange props aren't the same
function InvalidInput(props) {
  return (
    <InputMask mask="99/99/9999" value={props.value}>
      <MaterialInput type="tel" disableUnderline onChange={props.onChange} />
    </InputMask>
  );
}

Known Issues

Autofill

Browser's autofill requires either empty value in input or value which exactly matches beginning of the autofilled value. I.e. autofilled value "[phone]" will work with "+1" or "+1 (5", but won't work with "+1 (___) ___-____" or "1 (555)". There are several possible solutions:

1. Set maskChar to null and trim space after "+1" with beforeMaskedStateChange if no more digits are entered.
2. Apply mask only if value is not empty. In general, this is the most reliable solution because we can't be sure about formatting in autofilled value.
3. Use less formatting in the mask.

Please note that it might lead to worse user experience (should I enter +1 if input is empty?). You should choose what's more important to your users — smooth typing experience or autofill. Phone and ZIP code inputs are very likely to be autofilled and it's a good idea to care about it, while security confirmation code in two-factor authorization shouldn't care about autofill at all.

Cypress tests

The following sequence could fail

cy.get("input")
  .focus()
  .type("12345")
  .should("have.value", "12/34/5___"); // expected <input> to have value 12/34/5___, but the value was 23/45/____

Since focus is not an action command, it behaves differently than the real user interaction and, therefore, less reliable.

There is a few possible workarounds

// Start typing without calling focus() explicitly.
// type() is an action command and focuses input anyway
cy.get("input")
  .type("12345")
  .should("have.value", "12/34/5___");

// Use click() instead of focus()
cy.get("input")
  .click()
  .type("12345")
  .should("have.value", "12/34/5___");

// Or wait a little after focus()
cy.get("input")
  .focus()
  .wait(50)
  .type("12345")
  .should("have.value", "12/34/5___");

Thanks

Thanks to BrowserStack for the help with testing on real devices